home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / vtcl / doc / AddErrInfo.3 next >
Encoding:
Text File  |  1995-07-10  |  6.3 KB  |  151 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/AddErrInfo.3,v 1.15 93/04/08 13:54:29 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. '\"----------------------------------------------------------------------------
  24. '\"    @(#) AddErrInfo.3 26.1 93/10/22 SCOINC
  25. '\"
  26. '\"     Copyright (C) The Santa Cruz Operation, 1992-1993.
  27. '\"     This Module contains Proprietary Information of
  28. '\"    The Santa Cruz Operation, and should be treated as Confidential.
  29. '\"----------------------------------------------------------------------------
  30. .so ../man.macros
  31. .HS Tcl_AddErrorInfo tclc
  32. .BS
  33. .SH NAME
  34. Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
  35. .SH SYNOPSIS
  36. .nf
  37. \fB#include <tcl.h>\fR
  38. .sp
  39. \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
  40. .sp
  41. \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ...\fB (char *) NULL\fR)
  42. .sp
  43. char *
  44. \fBTcl_PosixError\fR(\fIinterp\fR)
  45. .SH ARGUMENTS
  46. .AS Tcl_Interp *message
  47. .AP Tcl_Interp *interp in
  48. Interpreter in which to record information.
  49. .AP char *message in
  50. Identifying string to record in \fBerrorInfo\fR variable.
  51. .AP char *element in
  52. String to record as one element of \fBerrorCode\fR variable.
  53. Last \fIelement\fR argument must be NULL.
  54. .BE
  55.  
  56. .SH DESCRIPTION
  57. .PP
  58. These procedures are used to manipulate two global variables
  59. that hold information about errors.
  60. The variable \fBerrorInfo\fR holds a stack trace of the
  61. operations that were in progress when an error occurred, and
  62. is intended to be human-readable.
  63. The variable \fBerrorCode\fR holds a list of items that
  64. are intended to be machine-readable.
  65. The first item in \fBerrorCode\fR identifies the class of
  66. .VS
  67. error that occurred (e.g. POSIX means an error occurred in
  68. .VE
  69. a POSIX system call) and additional elements in \fBerrorCode\fR
  70. hold additional pieces of information that depend on the class.
  71. See the Tcl overview manual entry for details on the various
  72. formats for \fBerrorCode\fR.
  73. .PP
  74. The \fBerrorInfo\fR variable is gradually built up as an
  75. error unwinds through the nested operations.
  76. Each time an error code is returned to \fBTcl_Eval\fR
  77. it calls the procedure \fBTcl_AddErrorInfo\fR to add
  78. additional text to \fBerrorInfo\fR describing the
  79. command that was being executed when the error occurred.
  80. By the time the error has been passed all the way back
  81. to the application, it will contain a complete trace
  82. of the activity in progress when the error occurred.
  83. .PP
  84. It is sometimes useful to add additional information to
  85. \fBerrorInfo\fR beyond what can be supplied automatically
  86. by \fBTcl_Eval\fR.
  87. \fBTcl_AddErrorInfo\fR may be used for this purpose:
  88. its \fImessage\fR argument contains an additional
  89. string to be appended to \fBerrorInfo\fR.
  90. For example, the \fBsource\fR command calls \fBTcl_AddErrorInfo\fR
  91. to record the name of the file being processed and the
  92. line number on which the error occurred;  for Tcl procedures, the
  93. procedure name and line number within the procedure are recorded,
  94. and so on.
  95. The best time to call \fBTcl_AddErrorInfo\fR is just after
  96. \fBTcl_Eval\fR has returned \fBTCL_ERROR\fR.
  97. In calling \fBTcl_AddErrorInfo\fR, you may find it useful to
  98. use the \fBerrorLine\fR field of the interpreter (see the
  99. \fBTcl_Interp\fR manual entry for details).
  100. .PP
  101. The procedure \fBTcl_SetErrorCode\fR is used to set the
  102. \fBerrorCode\fR variable.
  103. Its \fIelement\fR arguments give one or more strings to record
  104. in \fBerrorCode\fR:  each \fIelement\fR will become one item
  105. of a properly-formed Tcl list stored in \fBerrorCode\fR.
  106. \fBTcl_SetErrorCode\fR is typically invoked just before returning
  107. an error.
  108. If an error is returned without calling \fBTcl_SetErrorCode\fR
  109. then the Tcl interpreter automatically sets \fBerrorCode\fR
  110. to \fBNONE\fR.
  111. .PP
  112. \fBTcl_PosixError\fR
  113. .VS
  114. sets the \fBerrorCode\fR variable after an error in a POSIX kernel call.
  115. It reads the value of the \fBerrno\fR C variable and calls
  116. \fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the
  117. \fBPOSIX\fR format.
  118. In addition, \fBTcl_PosixError\fR returns a human-readable
  119. .VE
  120. diagnostic message for the error (this is the same value that
  121. will appear as the third element in \fBerrorCode\fR).
  122. It may be convenient to include this string as part of the
  123. error message returned to the application in \fIinterp->result\fR.
  124. .PP
  125. It is important to call the procedures described here rather than
  126. setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
  127. \fBTcl_SetVar\fR.
  128. The reason for this is that the Tcl interpreter keeps information
  129. about whether these procedures have been called.
  130. For example, the first time \fBTcl_AppendResult\fR is called
  131. for an error, it clears the existing value of \fBerrorInfo\fR
  132. and adds the error message in \fIinterp->result\fR to the variable
  133. before appending \fImessage\fR;  in subsequent calls, it just
  134. appends the new \fImessage\fR.
  135. When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
  136. that \fBerrorCode\fR has been set;  this allows the Tcl interpreter
  137. to set \fBerrorCode\fR to \fBNONE\fB if it receives an error return
  138. when \fBTcl_SetErrorCode\fR hasn't been called.
  139. .PP
  140. If the procedure \fBTcl_ResetResult\fR is called, it clears all
  141. of the state associated with \fBerrorInfo\fR and \fBerrorCode\fR
  142. (but it doesn't actually modify the variables).
  143. If an error had occurred, this will clear the error state to
  144. make it appear as if no error had occurred after all.
  145.  
  146. .SH "SEE ALSO"
  147. Tcl_ResetResult, Tcl_Interp
  148.  
  149. .SH KEYWORDS
  150. error, stack, trace, variable
  151.